# Monitor Resource

A monitor resource represents a monitor inside MaxScale that monitors one or
more servers.

[TOC]

## Resource Operations

The _:name_ in all of the URIs must be the name of a monitor in MaxScale.

### Get a monitor

```
GET /v1/monitors/:name
```

Get a single monitor.

#### Response

`Status: 200 OK`

```javascript
{{get("/v1/monitors/MariaDB-Monitor")}}
```

### Get all monitors

```
GET /v1/monitors
```

Get all monitors.

#### Response

`Status: 200 OK`

```javascript
{{get("/v1/monitors")}}
```

### Get monitor relationships

```
GET /v1/monitors/:name/relationships/servers
```

The _:type_ in the URI must be either _services_, for service
relationships, or _servers_, for server relationships.

#### Response

`Status: 200 OK`

```javascript
{{get("/v1/monitors/MariaDB-Monitor/relationships/servers")}}
```

### Create a monitor

```
POST /v1/monitors
```

Create a new monitor. The request body must define at least the following
fields.

* `data.id`
  * Name of the monitor

* `data.type`
  * Type of the object, must be `monitors`

* `data.attributes.module`
  * The monitor module to use

* `data.attributes.parameters.user`
  * The [`user`](../Getting-Started/Configuration-Guide.md#password) to use

* `data.attributes.parameters.password`
  * The [`password`](../Getting-Started/Configuration-Guide.md#password) to use

All monitor parameters can be defined at creation time.

The following example defines a request body which creates a new monitor and
assigns two servers to be monitored by it. It also defines a custom value for
the _monitor_interval_ parameter.

```javascript
{
    data: {
        "id": "test-monitor", // Name of the monitor
        "type": "monitors",
        "attributes": {
            "module": "mariadbmon", // The monitor uses the mariadbmon module
            "parameters": { // Monitor parameters
                "monitor_interval": 1000,
                "user": "maxuser,
                "password": "maxpwd"
            }
        },
        "relationships": { // List of server relationships that this monitor uses
            "servers": {
                "data": [ // This monitor uses two servers
                    {
                        "id": "server1",
                        "type": "servers"
                    },
                    {
                        "id": "server2",
                        "type": "servers"
                    }
                ]
            }
        }
    }
}
```

#### Response

Monitor is created:

`Status: 204 No Content`

### Update a monitor

```
PATCH /v1/monitors/:name
```

The request body must be a valid JSON document representing the modified
monitor.

### Modifiable Fields

The following standard server parameter can be modified.

- [user](../Monitors/Monitor-Common.md#user)
- [password](../Monitors/Monitor-Common.md#password)
- [monitor_interval](../Monitors/Monitor-Common.md#monitor_interval)
- [backend_connect_timeout](../Monitors/Monitor-Common.md#backend_connect_timeout)
- [backend_write_timeout](../Monitors/Monitor-Common.md#backend_write_timeout)
- [backend_read_timeout](../Monitors/Monitor-Common.md#backend_read_timeout)
- [backend_connect_attempts](../Monitors/Monitor-Common.md#backend_connect_attempts)

In addition to these standard parameters, the monitor specific parameters can
also be modified. Refer to the monitor module documentation for details on these
parameters.

#### Response

Monitor is modified:

`Status: 204 No Content`

Invalid request body:

`Status: 400 Bad Request`

### Update monitor relationships

```
PATCH /v1/monitors/:name/relationships/:type
```

The _:type_ in the URI must be either _services_, for service
relationships, or _servers_, for server relationships.

The request body must be a JSON object that defines only the _data_ field. The
value of the _data_ field must be an array of relationship objects that define
the _id_ and _type_ fields of the relationship. This object will replace the
existing relationships of the monitor.

The following is an example request and request body that defines a single
server relationship for a monitor.

```
PATCH /v1/monitors/my-monitor/relationships/servers

{
    data: [
          { "id": "my-server", "type": "servers" }
    ]
}
```

All relationships for a monitor can be deleted by sending an empty array as the
_data_ field value. The following example removes all servers from a monitor.

```
PATCH /v1/monitors/my-monitor/relationships/servers

{
    data: []
}
```

#### Response

Monitor relationships modified:

`Status: 204 No Content`

Invalid JSON body:

`Status: 400 Bad Request`

### Destroy a monitor

```
DELETE /v1/monitors/:name
```

Destroy a created monitor. The monitor must not have relationships to any
servers in order to be destroyed.

This endpoint also supports the `force=yes` parameter that will unconditionally
delete the monitor by first unlinking it from all servers that it uses.

#### Response

Monitor is deleted:

`Status: 204 No Content`

Monitor could not be deleted:

`Status: 400 Bad Request`

### Stop a monitor

```
PUT /v1/monitors/:name/stop
```

Stops a started monitor.

#### Response

Monitor is stopped:

`Status: 204 No Content`

### Start a monitor

```
PUT /v1/monitors/:name/start
```

Starts a stopped monitor.

#### Response

Monitor is started:

`Status: 204 No Content`
